package org.cybzacg.convert.annotation;

import org.cybzacg.convert.enums.CopyMode;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 属性拷贝注解
 * 用于标注字段或类，定义属性拷贝的配置和行为
 * 
 * @author PropertyCopier Implementation
 * @version 1.0.0
 */
@Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CopyProperty {
    
    /**
     * 字段名称映射
     * 当源对象和目标对象的字段名不同时，用于指定映射关系
     * 
     * @return 目标字段名称，默认为空字符串表示使用原字段名
     */
    String name() default "";
    
    /**
     * 是否必需字段
     * 标记字段是否为必需拷贝的字段
     * 
     * @return 如果为必需字段则返回true，默认为true
     */
    boolean required() default true;
    
    /**
     * 自定义转换器类
     * 指定用于该字段转换的自定义转换器类
     * 
     * @return 转换器类的全限定名，默认为空字符串表示使用默认转换器
     */
    String converter() default "";
    
    /**
     * 拷贝模式
     * 指定该字段的拷贝模式
     * 
     * @return 拷贝模式，默认为SHALLOW
     */
    CopyMode mode() default CopyMode.SHALLOW;
    
    /**
     * 字段描述
     * 用于描述字段的用途和拷贝规则
     * 
     * @return 字段描述，默认为空字符串
     */
    String description() default "";
    
    /**
     * 是否忽略null值
     * 当源字段值为null时，是否跳过拷贝
     * 
     * @return 如果忽略null值则返回true，默认为false
     */
    boolean ignoreNull() default false;
    
    /**
     * 是否只读字段
     * 标记字段是否为只读，只读字段不会被拷贝到目标对象
     * 
     * @return 如果为只读字段则返回true，默认为false
     */
    boolean readOnly() default false;
    
    /**
     * 拷贝优先级
     * 当有多个拷贝规则冲突时，优先级高的规则优先执行
     * 
     * @return 优先级值，数值越大优先级越高，默认为0
     */
    int priority() default 0;
    
    /**
     * 是否忽略类型不匹配
     * 当源字段和目标字段类型不匹配时，是否跳过拷贝
     * 
     * @return 如果忽略类型不匹配则返回true，默认为false
     */
    boolean ignoreTypeMismatch() default false;
    
    /**
     * 字段分组
     * 用于将字段分组，便于批量控制和过滤
     * 
     * @return 分组名称，默认为空字符串表示不分组
     */
    String group() default "";
    
    /**
     * 是否启用缓存
     * 对于复杂对象的拷贝结果是否进行缓存
     * 
     * @return 如果启用缓存则返回true，默认为false
     */
    boolean cacheable() default false;
    
    /**
     * 深度限制
     * 对于深拷贝模式，限制递归的最大深度
     * 
     * @return 最大深度，-1表示无限制，默认为-1
     */
    int maxDepth() default -1;
    
    /**
     * 条件表达式
     * 使用SpEL表达式定义拷贝条件
     * 
     * @return 条件表达式，默认为空字符串表示无条件
     */
    String condition() default "";
    
    /**
     * 是否启用懒加载
     * 对于大对象或复杂对象，是否启用懒加载模式
     * 
     * @return 如果启用懒加载则返回true，默认为false
     */
    boolean lazy() default false;
}
